From 98fab462b60962d5802da66a5d8dd916b8cf67cf Mon Sep 17 00:00:00 2001 From: jeroendedauw Date: Thu, 10 May 2012 21:22:11 +0200 Subject: [PATCH] add since tags Change-Id: I613fe006351c885420ff03a93cf2a239ca88831d --- includes/Content.php | 68 +++++++++++++++++++++++++++++- includes/ContentHandler.php | 68 +++++++++++++++++++++++++++++- includes/SecondaryDBDataUpdate.php | 10 +++++ includes/SecondaryDataUpdate.php | 9 ++++ includes/parser/ParserOutput.php | 4 ++ 5 files changed, 155 insertions(+), 4 deletions(-) diff --git a/includes/Content.php b/includes/Content.php index 162920352c..56221eae38 100644 --- a/includes/Content.php +++ b/includes/Content.php @@ -17,12 +17,16 @@ abstract class Content { protected $model_name; /** + * @since WD.1 + * * @return String a string representing the content in a way useful for building a full text search index. * If no useful representation exists, this method returns an empty string. */ public abstract function getTextForSearchIndex( ); /** + * @since WD.1 + * * @return String the wikitext to include when another page includes this content, or false if the content is not * includable in a wikitext page. * @@ -34,6 +38,8 @@ abstract class Content { /** * Returns a textual representation of the content suitable for use in edit summaries and log messages. * + * @since WD.1 + * * @param int $maxlength maximum length of the summary text * @return String the summary text */ @@ -43,6 +49,8 @@ abstract class Content { * Returns native represenation of the data. Interpretation depends on the data model used, * as given by getDataModel(). * + * @since WD.1 + * * @return mixed the native representation of the content. Could be a string, a nested array * structure, an object, a binary blob... anything, really. * @@ -68,6 +76,8 @@ abstract class Content { * Returns the name of the content model used by this content objects. * Corresponds to the CONTENT_MODEL_XXX constants. * + * @since WD.1 + * * @return String the model name */ public function getModelName() { @@ -92,6 +102,8 @@ abstract class Content { * * Shorthand for ContentHandler::getForContent( $this ) * + * @since WD.1 + * * @return ContentHandler */ public function getContentHandler() { @@ -104,6 +116,8 @@ abstract class Content { * * Shorthand for $this->getContentHandler()->getDefaultFormat() * + * @since WD.1 + * * @return ContentHandler */ public function getDefaultFormat() { @@ -116,6 +130,8 @@ abstract class Content { * * Shorthand for $this->getContentHandler()->getSupportedFormats() * + * @since WD.1 + * * @return array of supported serialization formats */ public function getSupportedFormats() { @@ -131,6 +147,8 @@ abstract class Content { * * Shorthand for $this->getContentHandler()->isSupportedFormat( $format ) * + * @since WD.1 + * * @param String $format the format to check * @return bool whether the format is supported */ @@ -159,6 +177,8 @@ abstract class Content { * * Shorthand for $this->getContentHandler()->serializeContent( $this, $format ) * + * @since WD.1 + * * @param null|String $format the desired serialization format (or null for the default format). * @return String serialized form of this Content object */ @@ -169,6 +189,8 @@ abstract class Content { /** * Returns true if this Content object represents empty content. * + * @since WD.1 + * * @return bool whether this Content object is empty */ public function isEmpty() { @@ -189,6 +211,8 @@ abstract class Content { * * $a->equals( $b ) <=> $b->equals( $b ) * * $a->equals( $b ) && $b->equals( $c ) ==> $a->equals( $c ) * + * @since WD.1 + * * @param Content $that the Content object to compare to * @return bool true if this Content object is euqual to $that, false otherwise. */ @@ -220,6 +244,8 @@ abstract class Content { * return $this. That is, $copy === $original may be true, but only for imutable content * objects. * + * @since WD.1 + * * @return Content. A copy of this object */ public abstract function copy( ); @@ -228,6 +254,8 @@ abstract class Content { * Returns true if this content is countable as a "real" wiki page, provided * that it's also in a countable location (e.g. a current revision in the main namespace). * + * @since WD.1 + * * @param $hasLinks Bool: if it is known whether this content contains links, provide this information here, * to avoid redundant parsing to find out. * @return boolean @@ -242,6 +270,8 @@ abstract class Content { * the result of calling getText() on the ParserOutput object returned by * this method is undefined. * + * @since WD.1 + * * @return ParserOutput */ public abstract function getParserOutput( IContextSource $context, $revId = null, ParserOptions $options = NULL, $generateHtml = true ); @@ -252,6 +282,8 @@ abstract class Content { * The last element in the array is the final destination after all redirects * have been resolved (up to $wgMaxRedirects times). * + * @since WD.1 + * * @return Array of Titles, with the destination last */ public function getRedirectChain() { @@ -264,6 +296,8 @@ abstract class Content { * This will only return the immediate redirect target, useful for * the redirect table and other checks that don't need full recursion. * + * @since WD.1 + * * @return Title: The corresponding Title */ public function getRedirectTarget() { @@ -276,14 +310,21 @@ abstract class Content { * This will recurse down $wgMaxRedirects times or until a non-redirect target is hit * in order to provide (hopefully) the Title of the final destination instead of another redirect. * + * @since WD.1 + * * @return Title */ public function getUltimateRedirectTarget() { return null; } + /** + * @since WD.1 + * + * @return bool + */ public function isRedirect() { - return $this->getRedirectTarget() != null; + return $this->getRedirectTarget() !== null; } /** @@ -291,6 +332,8 @@ abstract class Content { * * The default implementation returns null. * + * @since WD.1 + * * @param String $sectionId the section's id, given as a numeric string. The id "0" retrieves the section before * the first heading, "1" the text between the first heading (inluded) and the second heading (excluded), etc. * @return Content|Boolean|null the section, or false if no such section exist, or null if sections are not supported @@ -302,6 +345,8 @@ abstract class Content { /** * Replaces a section of the content and returns a Content object with the section replaced. * + * @since WD.1 + * * @param $section empty/null/false or a section number (0, 1, 2, T1, T2...), or "new" * @param $with Content: new content of the section * @param $sectionTitle String: new section's subject, only if $section is 'new' @@ -314,6 +359,8 @@ abstract class Content { /** * Returns a Content object with pre-save transformations applied (or this object if no transformations apply). * + * @since WD.1 + * * @param Title $title * @param User $user * @param null|ParserOptions $popts @@ -327,6 +374,8 @@ abstract class Content { * Returns a new WikitextContent object with the given section heading prepended, if supported. * The default implementation just returns this Content object unmodified, ignoring the section header. * + * @since WD.1 + * * @param $header String * @return Content */ @@ -337,6 +386,8 @@ abstract class Content { /** * Returns a Content object with preload transformations applied (or this object if no transformations apply). * + * @since WD.1 + * * @param Title $title * @param null|ParserOptions $popts * @return Content @@ -367,6 +418,8 @@ abstract class Content { * Content object implementation for representing flat text. * * TextContent instances are imutable + * + * @since WD.1 */ abstract class TextContent extends Content { @@ -472,6 +525,9 @@ abstract class TextContent extends Content { } +/** + * @since WD.1 + */ class WikitextContent extends TextContent { public function __construct( $text ) { @@ -677,6 +733,9 @@ class WikitextContent extends TextContent { } +/** + * @since WD.1 + */ class MessageContent extends TextContent { public function __construct( $msg_key, $params = null, $options = null ) { parent::__construct(null, CONTENT_MODEL_WIKITEXT); #XXX: messages may be wikitext, html or plain text! and maybe even something else entirely. @@ -718,7 +777,9 @@ class MessageContent extends TextContent { } - +/** + * @since WD.1 + */ class JavaScriptContent extends TextContent { public function __construct( $text ) { parent::__construct($text, CONTENT_MODEL_JAVASCRIPT); @@ -735,6 +796,9 @@ class JavaScriptContent extends TextContent { } +/** + * @since WD.1 + */ class CssContent extends TextContent { public function __construct( $text ) { parent::__construct($text, CONTENT_MODEL_CSS); diff --git a/includes/ContentHandler.php b/includes/ContentHandler.php index ac54be3686..410215622d 100644 --- a/includes/ContentHandler.php +++ b/includes/ContentHandler.php @@ -40,6 +40,8 @@ abstract class ContentHandler { * * If $wgContentHandlerTextFallback is 'ignore' and $content is not a TextContent object, this method returns null. * * otherwise, the behaviour is undefined. * + * @since WD.1 + * * @static * @param Content|null $content * @return null|string the textual form of $content, if available @@ -73,6 +75,8 @@ abstract class ContentHandler { * $text will be deserialized into a Content object of the model specified by $modelName (or, * if that is not given, $title->getContentModelName()) using the given format. * + * @since WD.1 + * * @static * @param string $text the textual represenation, will be unserialized to create the Content object * @param Title $title the title of the page this text belongs to, required as a context for deserialization @@ -110,6 +114,8 @@ abstract class ContentHandler { * * Note: this is used by, and may thus not use, Title::getContentModelName() * + * @since WD.1 + * * @static * @param Title $title * @return null|string default model name for the page given by $title @@ -178,6 +184,8 @@ abstract class ContentHandler { /** * returns the appropriate ContentHandler singleton for the given title * + * @since WD.1 + * * @static * @param Title $title * @return ContentHandler @@ -190,6 +198,8 @@ abstract class ContentHandler { /** * returns the appropriate ContentHandler singleton for the given Content object * + * @since WD.1 + * * @static * @param Content $content * @return ContentHandler @@ -213,6 +223,8 @@ abstract class ContentHandler { * If no ContentHandler is defined for the desired $modelName, the ContentHandler may be provided by the * a ContentHandlerForModelName hook. if no Contenthandler can be determined, an MWException is raised. * + * @since WD.1 + * * @static * @param $modelName String the name of the content model for which to get a handler. Use CONTENT_MODEL_XXX constants. * @return ContentHandler the ContentHandler singleton for handling the model given by $modelName @@ -259,6 +271,8 @@ abstract class ContentHandler { /** * Serializes Content object of the type supported by this ContentHandler. * + * @since WD.1 + * * @abstract * @param Content $content the Content object to serialize * @param null $format the desired serialization format @@ -269,6 +283,8 @@ abstract class ContentHandler { /** * Unserializes a Content object of the type supported by this ContentHandler. * + * @since WD.1 + * * @abstract * @param $blob String serialized form of the content * @param null $format the format used for serialization @@ -279,6 +295,8 @@ abstract class ContentHandler { /** * Creates an empty Content object of the type supported by this ContentHandler. * + * @since WD.1 + * * @return Content */ public abstract function makeEmptyContent(); @@ -287,6 +305,8 @@ abstract class ContentHandler { * Returns the model name that identifies the content model this ContentHandler can handle. * Use with the CONTENT_MODEL_XXX constants. * + * @since WD.1 + * * @return String the model name */ public function getModelName() { @@ -296,6 +316,8 @@ abstract class ContentHandler { /** * Throws an MWException if $modelName is not the content model handeled by this ContentHandler. * + * @since WD.1 + * * @param String $modelName the model name to check */ protected function checkModelName( $modelName ) { @@ -308,6 +330,8 @@ abstract class ContentHandler { * Returns a list of serialization formats supported by the serializeContent() and unserializeContent() methods of * this ContentHandler. * + * @since WD.1 + * * @return array of serialization formats as MIME type like strings */ public function getSupportedFormats() { @@ -320,6 +344,8 @@ abstract class ContentHandler { * This default implementation will return the first element of the array of formats * that was passed to the constructor. * + * @since WD.1 + * * @return String the name of the default serialiozation format as a MIME type */ public function getDefaultFormat() { @@ -333,6 +359,8 @@ abstract class ContentHandler { * Note that if $format is null, this method always returns true, because null * means "use the default format". * + * @since WD.1 + * * @param String $format the serialization format to check * @return bool */ @@ -363,6 +391,8 @@ abstract class ContentHandler { * (and only when) $wgActions[$action] === true. This allows subclasses * to override the default action handlers. * + * @since WD.1 + * * @return Array */ public function getActionOverrides() { @@ -375,6 +405,8 @@ abstract class ContentHandler { * NOTE: does *not* do special handling for Image and Category pages! * Use Article::newFromTitle() for that! * + * @since WD.1 + * * @param Title $title * @return Article * @todo Article is being refactored into an action class, keep track of that @@ -390,6 +422,8 @@ abstract class ContentHandler { /** * Return an EditPage object suitable for editing the given object * + * @since WD.1 + * * @param Article $article * @return EditPage */ @@ -403,6 +437,8 @@ abstract class ContentHandler { /** * Return an ExternalEdit object suitable for editing the given object * + * @since WD.1 + * * @param IContextSource $context * @return ExternalEdit * @todo does anyone or anythign actually use the external edit facility? Can we just deprecate and ignore it? @@ -416,6 +452,8 @@ abstract class ContentHandler { /** * Factory + * @since WD.1 + * * @param $context IContextSource context to use, anything else will be ignored * @param $old Integer old ID we want to show and diff with. * @param $new String either 'prev' or 'next'. @@ -438,7 +476,7 @@ abstract class ContentHandler { /** * Returns the name of the diff engine to use. * - * @since 0.1 + * @since WD.1 * * @return string */ @@ -452,6 +490,8 @@ abstract class ContentHandler { * * This default implementation always returns false. * + * @since WD.1 + * * @param $oldContent String * @param $myContent String * @param $yourContent String @@ -464,6 +504,8 @@ abstract class ContentHandler { /** * Return an applicable autosummary if one exists for the given edit. * + * @since WD.1 + * * @param $oldContent Content|null: the previous text of the page. * @param $newContent Content|null: The submitted text of the page. * @param $flags Int bitmask: a bitmask of flags submitted for the edit. @@ -526,6 +568,8 @@ abstract class ContentHandler { /** * Auto-generates a deletion reason * + * @since WD.1 + * * @param $title Title: the page's title * @param &$hasHistory Boolean: whether the page has a history * @return mixed String containing deletion reason or empty string, or boolean false @@ -621,9 +665,13 @@ abstract class ContentHandler { * Get the Content object that needs to be saved in order to undo all revisions * between $undo and $undoafter. Revisions must belong to the same page, * must exist and must not be deleted + * + * @since WD.1 + * * @param $current Revision the current text * @param $undo Revision the revision to undo * @param $undoafter Revision Must be an earlier revision than $undo + * * @return mixed string on success, false on failure */ public function getUndoContent( Revision $current, Revision $undo, Revision $undoafter ) { @@ -650,6 +698,8 @@ abstract class ContentHandler { * Returns true for content models that support caching using the ParserCache mechanism. * See WikiPage::isParserCacheUser(). * + * @since WD.1 + * * @return bool */ public function isParserCacheSupported() { @@ -657,6 +707,8 @@ abstract class ContentHandler { } /** + * @since WD.1 + * * @param $page WikiPage the page that was deleted (note: $page->getId() must still return the old page ID!) * * @return array a list of SecondaryDataUpdate instances that will clean up the database ofter deletion. @@ -668,7 +720,9 @@ abstract class ContentHandler { } } - +/** + * @since WD.1 + */ abstract class TextContentHandler extends ContentHandler { public function __construct( $modelName, $formats ) { @@ -720,6 +774,10 @@ abstract class TextContentHandler extends ContentHandler { } + +/** + * @since WD.1 + */ class WikitextContentHandler extends TextContentHandler { public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) { @@ -741,6 +799,9 @@ class WikitextContentHandler extends TextContentHandler { #XXX: make ScriptContentHandler base class with plugin interface for syntax highlighting? +/** + * @since WD.1 + */ class JavaScriptContentHandler extends TextContentHandler { public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) { @@ -758,6 +819,9 @@ class JavaScriptContentHandler extends TextContentHandler { } } +/** + * @since WD.1 + */ class CssContentHandler extends TextContentHandler { public function __construct( $modelName = CONTENT_MODEL_WIKITEXT ) { diff --git a/includes/SecondaryDBDataUpdate.php b/includes/SecondaryDBDataUpdate.php index babe4057b3..3fff383c60 100644 --- a/includes/SecondaryDBDataUpdate.php +++ b/includes/SecondaryDBDataUpdate.php @@ -19,6 +19,8 @@ * * Abstract base class for update jobs that put some secondary data extracted * from article content into the database. + * + * @since WD.1 */ abstract class SecondaryDBDataUpdate extends SecondaryDataUpdate { @@ -52,6 +54,8 @@ abstract class SecondaryDBDataUpdate extends SecondaryDataUpdate { * * Because nested transactions are not supportred by the Database class, this implementation * checked Database::trxLevel() and only opens a transaction if none is yet active. + * + * @since WD.1 */ public function beginTransaction() { // NOTE: nested transactions are not supported, only start a transaction if none is open @@ -63,6 +67,8 @@ abstract class SecondaryDBDataUpdate extends SecondaryDataUpdate { /** * Commit the database transaction started via beginTransaction (if any). + * + * @since WD.1 */ public function commitTransaction() { if ( $this->mHasTransaction ) { @@ -72,6 +78,8 @@ abstract class SecondaryDBDataUpdate extends SecondaryDataUpdate { /** * Abort the database transaction started via beginTransaction (if any). + * + * @since WD.1 */ public function abortTransaction() { if ( $this->mHasTransaction ) { @@ -83,6 +91,8 @@ abstract class SecondaryDBDataUpdate extends SecondaryDataUpdate { * Invalidate the cache of a list of pages from a single namespace. * This is intended for use by subclasses. * + * @since WD.1 + * * @param $namespace Integer * @param $dbkeys Array */ diff --git a/includes/SecondaryDataUpdate.php b/includes/SecondaryDataUpdate.php index 53da6b49b0..f89f6911ba 100644 --- a/includes/SecondaryDataUpdate.php +++ b/includes/SecondaryDataUpdate.php @@ -22,6 +22,7 @@ * * @todo: add support for transactions * + * @since WD.1 */ abstract class SecondaryDataUpdate implements DeferrableUpdate { @@ -35,6 +36,8 @@ abstract class SecondaryDataUpdate implements DeferrableUpdate { /** * Begin an appropriate transaction, if any. * This default implementation does nothing. + * + * @since WD.1 */ public function beginTransaction() { //noop @@ -43,6 +46,8 @@ abstract class SecondaryDataUpdate implements DeferrableUpdate { /** * Commit the transaction started via beginTransaction, if any. * This default implementation does nothing. + * + * @since WD.1 */ public function commitTransaction() { //noop @@ -51,6 +56,8 @@ abstract class SecondaryDataUpdate implements DeferrableUpdate { /** * Abort / roll back the transaction started via beginTransaction, if any. * This default implementation does nothing. + * + * @since WD.1 */ public function rollbackTransaction() { //noop @@ -68,6 +75,8 @@ abstract class SecondaryDataUpdate implements DeferrableUpdate { * This allows for limited transactional logic across multiple baceknds for storing * secondary data. * + * @since WD.1 + * * @static * @param $updates array a list of SecondaryDataUpdate instances */ diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php index 906690b70c..ad3a986eea 100644 --- a/includes/parser/ParserOutput.php +++ b/includes/parser/ParserOutput.php @@ -455,6 +455,8 @@ class ParserOutput extends CacheTime { * Adds an update job to the output. Any update jobs added to the output will eventually bexecuted in order to * store any secondary information extracted from the page's content. * + * @since WD.1 + * * @param SecondaryDataUpdate $update */ public function addSecondaryDataUpdate( SecondaryDataUpdate $update ) { @@ -466,6 +468,8 @@ class ParserOutput extends CacheTime { * extracted from the page's content, includingt a LinksUpdate object for all links stopred in * this ParserOutput object. * + * @since WD.1 + * * @param $title Title of the page we're updating. If not given, a title object will be created based on $this->getTitleText() * @param $recursive Boolean: queue jobs for recursive updates? * -- 2.20.1